<!-- .\" $Id: papi_encode_events.html,v 1.1.2.1 2006/10/27 19:47:13 terpstra Exp $ -->
<!-- .TH PAPI_encode_events 3 "October, 2006" "PAPI Programmer's Reference" PAPI -->
<HTML>
<HEAD>
<TITLE>
Manual Page - PAPI_encode_events(3)</TITLE>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">

<STYLE TYPE="text/css">

<!--

p

{font-family: Verdana, Helvetica, Arial, sans-serif}



.style

{font-family: Verdana, Helvetica, Arial, sans-serif}



td.navBar A:link

{color: #ddd8d2;

font-weight: bold;

text-decoration: none}



td.navBar A:visited

{color: #ccc9c5;

font-weight: bold;

text-decoration: none}



td.navBar A:hover

{color: #ffffff}



.navBar

{color: #77797c;

font-family: Verdana, Helvetica, Arial, sans-serif;

font-size:  11px;

text-transform: uppercase}



a:visited

{color: #50525f}



a:link

{color: #8b3409}



a:hover

{color: #660000}



a:active

{background-color: #b1afad}



.footerNote

{background-color: #ffffff;

background-image: url(../images/line.gif);

background-position: right top;

background-repeat: repeat-x;

color: #77797c;

font-family: Verdana, Helvetica, Arial, sans-serif;

font-size:  10px}



BODY

{font-family: Verdana, Helvetica, Arial, sans-serif}

-->

</STYLE> <SCRIPT LANGUAGE="JavaScript">

<!--

function MM_swapImgRestore() { //v3.0

  var i,x,a=document.MM_sr; for(i=0;a&&i<a.length&&(x=a[i])&&x.oSrc;i++) x.src=x.oSrc;

}



function MM_preloadimages() { //v3.0

  var d=document; if(d.images){ if(!d.MM_p) d.MM_p=new Array();

    var i,j=d.MM_p.length,a=MM_preloadimages.arguments; for(i=0; i<a.length; i++)

    if (a[i].indexOf("#")!=0){ d.MM_p[j]=new Image; d.MM_p[j++].src=a[i];}}

}



function MM_findObj(n, d) { //v4.0

  var p,i,x;  if(!d) d=document; if((p=n.indexOf("?"))>0&&parent.frames.length) {

    d=parent.frames[n.substring(p+1)].document; n=n.substring(0,p);}

  if(!(x=d[n])&&d.all) x=d.all[n]; for (i=0;!x&&i<d.forms.length;i++) x=d.forms[i][n];

  for(i=0;!x&&d.layers&&i<d.layers.length;i++) x=MM_findObj(n,d.layers[i].document);

  if(!x && document.getElementById) x=document.getElementById(n); return x;

}



function MM_swapImage() { //v3.0

  var i,j=0,x,a=MM_swapImage.arguments; document.MM_sr=new Array; for(i=0;i<(a.length-2);i+=3)

   if ((x=MM_findObj(a[i]))!=null){document.MM_sr[j++]=x; if(!x.oSrc) x.oSrc=x.src; x.src=a[i+2];}

}

//-->

</SCRIPT> 

</HEAD>

<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LEFTMARGIN="0" TOPMARGIN="0" MARGINWIDTH="0" MARGINHEIGHT="0">

<TABLE WIDTH="101%" BORDER="0" CELLSPACING="0" CELLPADDING="0">

<TR>

<TD VALIGN="top" HEIGHT="75">

<TABLE WIDTH="100%" BORDER="0" CELLSPACING="0" CELLPADDING="0" HEIGHT="75">

<TR>

<TD BACKGROUND="../images/menubg95.jpg" HEIGHT="75">

<TABLE WIDTH="760" BORDER="0" CELLSPACING="0" CELLPADDING="0" ALIGN="center" HEIGHT="75">

<TR VALIGN="bottom">

<TD WIDTH="760" ALIGN="center" HEIGHT="50" COLSPAN="2">

<IMG SRC="../images/headertop.jpg" WIDTH="760" HEIGHT="50"></TD>

</TR>

<TR>

<TD HEIGHT="10" ALIGN="center" VALIGN="top" BGCOLOR="#333333" WIDTH="135">

<IMG SRC="../images/logoleft.jpg" WIDTH="135" HEIGHT="25" VSPACE="0" HSPACE="0" ALIGN="left">

</TD>

<TD CLASS="navBar" HEIGHT="25" ALIGN="center" VALIGN="middle" BGCOLOR="#333333" NOWRAP WIDTH="625" BACKGROUND="../images/menubg.jpg">

<CENTER>

<A HREF="http://icl.cs.utk.edu/papi/">

PAPI HOME

</A>

</CENTER>

</TD>

</TR>

<TR>

<TD HEIGHT="10" ALIGN="center" VALIGN="top" BGCOLOR="FFFFFF" WIDTH="135">

<IMG SRC="../images/logobottom.jpg" WIDTH="135" HEIGHT="20" VSPACE="0" HSPACE="0" ALIGN="left">

</TD>

<TD CLASS="navBar" HEIGHT="10" ALIGN="center" VALIGN="bottom" BGCOLOR="FFFFFF" WIDTH="625">

<IMG SRC="../images/white.jpg" WIDTH="625" HEIGHT="20" VSPACE="0" HSPACE="0" ALIGN="left">

</TD>

</TR>

</TABLE>

</TD>

</TR>

</TABLE>

</TD>

</TR>

<TR>

<TD VALIGN="top">

<TABLE WIDTH="760" BORDER="0" CELLSPACING="0" CELLPADDING="0" ALIGN="center" CLASS="style">

<TR>

<TD CLASS="STYLE">

<P>
<!-- .SH NAME -->
<A name=0>

     <H3>NAME</H3>

</A>
<BLOCKQUOTE>
PAPI_encode_events - read event definitions from a file and modify the existing PAPI preset table.
<P>
<!-- .SH SYNOPSIS -->
</BLOCKQUOTE>
<A name=contents></A><H3>CONTENTS</H3></A>
<BLOCKQUOTE>
<A HREF=#1>Synopsis</A><BR>
<A HREF=#2>Description</A><BR>
<A HREF=#3>File Format</A><BR>
<A HREF=#4>Arguments</A><BR>
<A HREF=#5>Return Values</A><BR>
<A HREF=#6>Errors</A><BR>
<A HREF=#7>Example</A><BR>
<A HREF=#8>Bugs</A><BR>
<A HREF=#9>See Also</A><BR>
</BLOCKQUOTE>
<A name=10>

     <H3>SYNOPSIS</H3>

</A>
<BLOCKQUOTE>
<!-- .B C Interface -->
<B>C Interface</B> <!-- .nf -->
<PRE>
<!-- .B #include <papi.h> -->
<B>#include &lt;papi.h&gt;</B> 
<!-- .BI "int PAPI_encode_events(char * event_file, int replace);" -->
<B>int PAPI_encode_events(char * event_file, int replace);</B> 
<!-- .fi -->
</PRE>
<P>
<!-- .SH DESCRIPTION -->
</BLOCKQUOTE>
<A name=2>

     <H3>DESCRIPTION</H3>

</A>
<BLOCKQUOTE>
<!-- .B NOTE: This API has been deprecated in PAPI 3.5 pending a data structure redesign. -->
<B>NOTE: This API has been deprecated in PAPI 3.5 pending a data structure redesign.</B> <P>
This function reads event descriptions from a file where they are stored in comma separated value format
and modifies or adds events to the PAPI preset event table. The file format is described below.
This function presently works only to define or modify PAPI preset events.
<P>
<!-- .SH FILE FORMAT -->
</BLOCKQUOTE>
<A name=3>

     <H3>FILE FORMAT</H3>

</A>
<BLOCKQUOTE>
The comma separated value file format is one that can be easily edited in a standard text editor or
a csv-aware spreadsheet application, and can be easily parsed. Text strings can contain commas, but only if
the strings are enclosed in quotes. Each entry in the file is a separate line, and each field, including empty
fields, is separated by a comma from its neighbor. The specific format used in this case consists of a title
line for readability, a blank line, and a series of lines containing event definitions. A portion of such a
file (for Pentium 4) is shown below:
<P>
<!-- .nf -->
<PRE>
<!-- .if t .ft CW -->
<TT>name,derived,postfix,short_descr,long_descr,note,[native,...]
<P>
PAPI_L1_ICM,NOT_DERIVED,,"L1I cache misses","Level 1 instruction cache misses",,BPU_fetch_request_TCMISS
PAPI_L2_TCM,NOT_DERIVED,,"L2 cache misses","Level 2 cache misses",,BSQ_cache_reference_RD_2ndL_MISS_WR_2ndL_MISS
PAPI_TLB_DM,NOT_DERIVED,,"Data TLB misses","Data translation lookaside buffer misses",,page_walk_type_DTMISS
MY_PAPI_TLB_DM,NOT_DERIVED,,"Data TLB misses","Data translation lookaside buffer misses","This is a note for my event",page_walk_type_DTMISS
<!-- .if t .ft P -->
</TT><!-- .fi -->
</PRE>
<P>
<P>
<!-- .SH ARGUMENTS -->
</BLOCKQUOTE>
<A name=4>

     <H3>ARGUMENTS</H3>

</A>
<BLOCKQUOTE>
<!-- .LP -->
<P>
<!-- .I event_file -->
<I>event_file</I> --  string containing the name of the csv event file to be read
<!-- .LP -->
<P>
<!-- .I replace -->
<I>replace</I> --  1 to replace existing events, or 0 to prevent accidental replacement
<P>
<!-- .SH RETURN VALUES -->
</BLOCKQUOTE>
<A name=5>

     <H3>RETURN VALUES</H3>

</A>
<BLOCKQUOTE>
On success, the function returns
<!-- .B PAPI_OK. -->
<B>PAPI_OK.</B> On error, a non-zero error code is returned by the function.
<P>
<!-- .SH ERRORS -->
</BLOCKQUOTE>
<A name=6>

     <H3>ERRORS</H3>

</A>
<BLOCKQUOTE>
<!-- .TP -->
<TABLE cellpadding=3>
<TR valign=top><TD colspan=2>
<!-- .B "PAPI_EPERM" -->
<B>PAPI_EPERM</B> </TD></TR><TR valign=top><TD width=6%>&nbsp;</TD><TD>
You are trying to modify an existing event without specifying
<!-- .I replace. -->
<I>replace.</I> <!-- .TP -->
</TD></TR>
<TR valign=top><TD colspan=2>
<!-- .B "PAPI_EISRUN" -->
<B>PAPI_EISRUN</B> </TD></TR><TR valign=top><TD width=6%>&nbsp;</TD><TD>
You are trying to modify an event that has been added to an EventSet.
<!-- .TP -->
</TD></TR>
<TR valign=top><TD colspan=2>
<!-- .B "PAPI_EINVAL" -->
<B>PAPI_EINVAL</B> </TD></TR><TR valign=top><TD width=6%>&nbsp;</TD><TD>
One or more of the arguments or fields of the info structure is invalid.
<!-- .TP -->
</TD></TR>
<TR valign=top><TD colspan=2>
<!-- .B "PAPI_ENOTPRESET" -->
<B>PAPI_ENOTPRESET</B> </TD></TR><TR valign=top><TD width=6%>&nbsp;</TD><TD>
The PAPI preset table is full and there is no room for a new event.
<!-- .TP -->
</TD></TR>
<TR valign=top><TD colspan=2>
<!-- .B "PAPI_ENOEVNT" -->
<B>PAPI_ENOEVNT</B> </TD></TR><TR valign=top><TD width=6%>&nbsp;</TD><TD>
The event specified is not a PAPI preset. Usually because the PAPI_PRESET_MASK bit is not set.
<P>
<!-- .SH EXAMPLE -->
</TD></TR>
<TR></TR></TABLE></BLOCKQUOTE>
<A name=7>

     <H3>EXAMPLE</H3>

</A>
<BLOCKQUOTE>
<!-- .LP -->
<P>
<!-- .nf -->
<PRE>
<!-- .if t .ft CW -->
<TT>/* Use the command line utility to create a csv copy of the currently defined events */
&gt; /papi/utils/decode -a -&gt; current.csv
/* View and modify the events in an editor */
&gt; vi current.csv
<!-- ... -->
<!-- ignored unsupported tag ... -->
/* Load the modified events into the preset table */
if (PAPI_encode_events("./current.csv", 1) != PAPI_OK)
  handle_error(1);
<!-- .if t .ft P -->
</TT><!-- .fi -->
</PRE>
<P>
<!-- .SH BUGS -->
</BLOCKQUOTE>
<A name=8>

     <H3>BUGS</H3>

</A>
<BLOCKQUOTE>
This function has no known bugs.
<P>
<!-- .SH SEE ALSO -->
</BLOCKQUOTE>
<A name=9>

     <H3>SEE ALSO</H3>

</A>
<BLOCKQUOTE>
<!-- .BR papi_decode "(1)", -->
<A HREF="papi_decode.html">papi_decode (1)</A>
, 
<!-- .BR PAPI "(3),"  -->
<A HREF="papi.html">PAPI (3)</A>,
<!-- .BR PAPIF "(3),"  -->
<A HREF="papif.html">PAPIF (3)</A>,
<!-- .BR PAPI_get_event_info "(3)", -->
<A HREF="papi_get_event_info.html">PAPI_get_event_info (3)</A>
, 
<!-- .BR PAPI_set_event_info "(3)" -->
<A HREF="papi_set_event_info.html">PAPI_set_event_info (3)</A>
</BLOCKQUOTE>
<P><HR>
<TABLE width=100%><TR> <TD width=33%><I>PAPI Programmer&#146;s Reference</I></TD> <TD width=33% align=center>PAPI_encode_events (3)</TD> <TD align=right width=33%><I>October, 2006</I></TD> </TR></TABLE>
<HR SIZE="1">

</TD>

</TR>

</TABLE>

</TD>

</TR>

<TR>

<TD VALIGN="top">

<TABLE WIDTH="760" BORDER="0" CELLSPACING="0" CELLPADDING="5" ALIGN="center">

<TR>

<TD>

</TD>

</TR>

<TR>

<TD HEIGHT="92">

<TABLE WIDTH="760" BORDER="0" CELLSPACING="0" CELLPADDING="0" ALIGN="center" VSPACE="0" HSPACE="0">

<TR VALIGN="top">

<TD ALIGN="left" BACKGROUND="../images/stripes2.jpg" ROWSPAN="2">&nbsp;

 

</TD>

<TD ALIGN="right" HEIGHT="39" BACKGROUND="../images/stripes2.jpg" WIDTH="280">

<IMG SRC="../images/trans.gif" WIDTH="280" HEIGHT="63" VSPACE="0" HSPACE="0">

</TD>

<TD ALIGN="left" HEIGHT="63" WIDTH="200" BACKGROUND="../images/spinbg.jpg">

<A HREF="http://icl.cs.utk.edu/" ONMOUSEOUT="MM_swapImgRestore()" ONMOUSEOVER="MM_swapImage('Image10','','../images/spinlogo.gif',1)">

<IMG NAME="Image10" BORDER="0" SRC="../images/stable.gif" WIDTH="200" HEIGHT="63" HSPACE="0" VSPACE="0" ALIGN="left" ALT="Innovative Computing Laboratory">

</A>

</TD>

<TD ALIGN="left" HEIGHT="0" ROWSPAN="2" VALIGN="top" WIDTH="140">

<DIV ALIGN="left">

<IMG SRC="../images/trans.gif" WIDTH="140" HEIGHT="75" BORDER="0" ALIGN="left" VSPACE="0" HSPACE="0">

</DIV>

</TD>

<TD ALIGN="left" ROWSPAN="2" VALIGN="top" WIDTH="140">

<IMG SRC="../images/rd.jpg" WIDTH="140" HEIGHT="75" BORDER="0" ALIGN="right" VSPACE="0" HSPACE="0" ALT="2001 R&amp;D Winner">

</TD>

<TD ALIGN="right" ROWSPAN="3" VALIGN="top" BGCOLOR="#FFFFFF">&nbsp;

 

</TD>

</TR>

<TR VALIGN="top">

<TD ALIGN="center" HEIGHT="22" ROWSPAN="2" VALIGN="TOP">

<SPAN CLASS="FOOTERNOTE">

Contact PAPI: 

<A HREF="mailto:papi@cs.utk.edu">

papi@cs.utk.edu</A>

</SPAN>

</TD>

<TD ALIGN="center" HEIGHT="11" WIDTH="200">

<A HREF="http://www.cs.utk.edu/" ONMOUSEOUT="MM_swapImgRestore()" ONMOUSEOVER="MM_swapImage('Image11','','../images/cssigon.gif',1)">

<IMG NAME="Image11" BORDER="0" SRC="../images/cssigoff.gif" WIDTH="200" HEIGHT="11" ALIGN="left" HSPACE="0" VSPACE="0" ALT="Computer Science Department">

</A>

</TD>

</TR>

<TR VALIGN="top">

<TD ALIGN="left">&nbsp;

 

</TD>

<TD ALIGN="CENTER" HEIGHT="11" WIDTH="200" VALIGN="top">

<A HREF="http://www.utk.edu/" ONMOUSEOUT="MM_swapImgRestore()" ONMOUSEOVER="MM_swapImage('Image12','','../images/utsigon.gif',1)">

<IMG NAME="Image12" BORDER="0" SRC="../images/utsigoff.gif" WIDTH="200" HEIGHT="11" VSPACE="0" HSPACE="0" ALIGN="left" ALT="University of Tennessee">

</A>

</TD>

<TD ALIGN="left" HEIGHT="0" COLSPAN="2" VALIGN="top">&nbsp;

 

</TD>

</TR>

</TABLE>

</TD>

</TR>

</TABLE>

</TD>

</TR>

<TR>

<TD VALIGN="top">&nbsp;

 

</TD>

</TR>

</TABLE>

</BODY>

</HTML>

